home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 038a / bpp10.zip / BPP.DOC next >
Text File  |  1991-10-15  |  14KB  |  290 lines
  1.                           BPP: A BASIC PreProcessor                     page 1
  2.                           =-----------------------=
  3.                                  Version 1.0
  4.  
  5.                BPP  Copyright (c) 1991  Thomas G. Hanlin III
  6.  
  7.  
  8.  
  9. BPP processes your BASIC source code before the BASIC compiler or interpreter
  10. does.  This allows it to handle new commands that can affect how the code is
  11. handled.  Among the capabilities provided are name substititions, conditional
  12. compilation, underscores in variable names, and "include" files with few
  13. limitations.  BPP will work with QuickBASIC, BASCOM (including "PDS", the
  14. Professional Development System), and QBASIC (the BASIC "interpreter" that
  15. comes with DOS 5.0 and Microsoft's "Learn BASIC Now").  BPP may well work
  16. with other BASIC versions too.
  17.  
  18. If you've worked with C, you may be familiar with the power a preprocessor
  19. provides.  The current Turbo Pascal compiler also has limited preprocessor
  20. support.  For some reason, the idea hasn't yet crept into Microsoft's BASICs,
  21. so I decided to remedy that.  As I consider this a basic step in improving
  22. the state of the art in BASIC, this utility is free.  However, BPP is
  23. protected by copyright and may be distributed only if the following
  24. conditions are met:
  25.  
  26.    1) No fee of over $10.00 may be charged for distribution.  This
  27.       restriction applies only to physical copies and is not meant to
  28.       prevent distribution by commercial telecommunication services.
  29.  
  30.    2) All BPP files must be distributed together in original, unaltered
  31.       form.  This includes BPP.DOC, BPP.EXE, CATALOG.TXT, PRODUCT.TXT,
  32.       REGISTER.TXT, and WHERE.BBS.
  33.  
  34.    3) These files must be distributed as an individual unit.  It may not be
  35.       included as a part of other archives, and no files may be added to it.
  36.       It may be included with other archives, however.  The main intent here
  37.       is to preserve the original integrity of my files.  NOTE that this
  38.       clause very specifically means that BBS sysops may not add advertising
  39.       files to BPP.  I do not wish to be a vehicle for "junk mail".
  40.  
  41. You use this utility at your own risk.  It has been tested by me on my own
  42. computer, but I will not assume any responsibility for any problems which BPP
  43. may cause you.  If you do encounter a problem, please let me know about it,
  44. and I will do my best to verify and repair the error.
  45.  
  46. If you like BPP, perhaps you might be interested in one of my shareware
  47. libraries for BASIC.  See the CATALOG.TXT, PRODUCT.TXT, and REGISTER.TXT
  48. files for more information.
  49.  
  50.                               Table of Contents                         page 2
  51.  
  52.  
  53.  
  54.  Overview and Legal Info ................................................ 1
  55.  
  56.  General Usage Notes .................................................... 3
  57.  
  58.  Language Information ................................................... 4
  59.  
  60.  Some Suggested Uses .................................................... 6
  61.  
  62.  Miscellaneous Notes .................................................... 7
  63.  
  64.                            BPP: General Usage Notes                     page 3
  65.                            =----------------------=
  66.  
  67.  
  68.  
  69.  
  70. The BPP utility expects you to pass it at least a filename.  The default
  71. extension for the input file is ".B" and the default for the output file is
  72. ".BAS".  The output file will have the same name as the input file, just a
  73. different extension.  If the output file already exists, you will be asked
  74. whether to overwrite it by default.  This can be overridden with command-line
  75. switches.
  76.  
  77. Several options are available through command-line switches.  You may specify
  78. /O to always overwrite any existing .BAS file or /NO to never overwrite any
  79. existing .BAS file.  You may also define preprocessor variables as if they
  80. had been defined with a #DEFINE in your program, using /Dvarname.  This does
  81. not provide for giving a variable a specific value yet, just for defining it.
  82.  
  83. Preprocessor Syntax:
  84.  
  85.    BPP infile[.ext] [/option] [.../option]
  86.  
  87. Command-line options may be placed at any point on the command line.  If one
  88. option conflicts with another, the last one listed will have precedence over
  89. any prior options.
  90.  
  91.                           BPP: Language Information                     page 4
  92.                           =-----------------------=
  93.  
  94.  
  95.  
  96.  
  97. Preprocessor directives must always begin at the start of a line.  A pound
  98. sign is used to tell the preprocessor to expect a command.  I'll list the
  99. valid commands first, then explain a bit more about them.
  100.  
  101. Command Format                        Example Usage
  102. =====================                 ===================================
  103. #                                     #
  104. #DEFINE varname value                 #DEFINE Hello PRINT "Hi there!"
  105. #ENDIF                                #ENDIF
  106. #ERROR message                        #ERROR Did we forget something?!
  107. #IFDEF varname                        #IFDEF PDS
  108. #IFNDEF varname                       #IFNDEF PDS
  109. #INCLUDE filename                     #INCLUDE BASWIZ.BI
  110. #PRAGMA pragmadef                     #PRAGMA extendvar
  111. #UNDEF varname                        #UNDEF PDS
  112.  
  113. A "#" by itself has no meaning.  It can be used to help set off a section of
  114. preprocessor commands.
  115.  
  116. The #DEFINE command is used to define a variable.  The value is optional and
  117. is only meaningful if you have enabled name replacement with the appropriate
  118. #PRAGMA.  A value may be either a string or a number.  Variables can be
  119. redefined at a later point in the program.  Variable names may be up to 32
  120. characters long, must start with a letter, and can contain both letters and
  121. digits.  Underscores can also be used within variable names if the proper
  122. #PRAGMA has been defined.  There are four special variables defined by the
  123. preprocessor itself:
  124.  
  125.    __DATE__    the date at which processing started
  126.    __FILE__    the name of the file currently being processed
  127.    __LINE__    the current line number being processed in the current file
  128.    __TIME__    the time at which processing started
  129.  
  130. The #ENDIF command is used to terminate a conditional block.  It's the
  131. command used to tell the preprocessor that it's reached the end of a block
  132. that was started by #IFDEF or #IFNDEF.
  133.  
  134. The #ERROR command is used to halt the preprocessor.  On encountering an
  135. #ERROR command, the preprocessor halts, generating an error message with the
  136. current filename and line number.  You may optionally include an error
  137. message of your own as well.  This command is useful for debugging when you
  138. have a complex set of preprocessor instructions.
  139.  
  140.                           BPP: Language Information                     page 5
  141.                           =-----------------------=
  142.  
  143.  
  144.  
  145.  
  146. An #IFDEF statement tells the preprocessor to handle the following lines only
  147. if a variable has been defined.  An #IFDEF block is terminated when the
  148. preprocessor reaches an #ENDIF command.  Nested #IFDEF blocks are allowed.
  149.  
  150. The opposite of this is an #IFNDEF statement, which tells the preprocessor to
  151. handle the following lines only if a variable has NOT been defined.  An
  152. #IFNDEF block is terminated when the preprocessor reaches an #ENDIF command.
  153. Nested #IFNDEF blocks are allowed.
  154.  
  155. The #INCLUDE command allows you to include the contents of a specified file
  156. in your program.  This is like the REM $INCLUDE metacommand supported by
  157. QuickBASIC and BASCOM (but not QBASIC), but does not mind if you include SUBs
  158. and FUNCTIONs in the include file.  Include files may be nested to a depth of
  159. about 14 (files are left open for quicker processing, so each nested include
  160. requires an additional file handle).  The extension ".BI" will be assumed if
  161. no extension is given.  If the include file can't be found in the default
  162. directory, the preprocessor will look in the directory specified by the
  163. INCLUDE environment variable, if any.  In other words, this works just like
  164. REM $INCLUDE, only better.
  165.  
  166. The #PRAGMA statement turns various options on or off.  At the moment, there
  167. are two options:
  168.  
  169.    EXTENDVAR     Allows you to use underscores (the "_" character) in the
  170.                  middle of variable names (both BASIC and preprocessor
  171.                  variables are affected).  Underscores will be stripped out
  172.                  by the preprocessor, so they're just for cosmetic value.
  173.  
  174.    EXTENDPARSE   Enables name replacement (and in later versions of BPP,
  175.                  probably macros).  With name replacement, any occurrence of
  176.                  a preprocessor variable in your code is replaced by the
  177.                  value of the preprocessor variable.  This is powerful, but
  178.                  processing is much slower with this capability turned on.
  179.  
  180. You can use "!" before an option to turn it off.  The defaults, if no #PRAGMA
  181. is used, are !EXTENDVAR and !EXTENDPARSE (both options are off).
  182.  
  183. The #UNDEF command is used to undefine a variable.  A variable that has been
  184. undefined is treated as if doesn't exist from then on.  It can be redefined
  185. at a later point using #DEFINE.
  186.  
  187.                            BPP: Some Suggested Uses                     page 6
  188.                            =----------------------=
  189.  
  190.  
  191.  
  192.  
  193. The #PRAGMA EXTENDVAR directive allows you to make your programs much more
  194. readable.  Instead of using a variable like GROSSADJUSTEDPROFIT, you can say
  195. GROSS_ADJUSTED_PROFIT, which gets the idea across much better.  Keep in mind
  196. that the underscores will be stripped out, however, so they will not serve to
  197. distinguish between two variables which have the same names except for the
  198. underscores.  The EXTENDVAR handling will not interfere with underscores that
  199. are in REM or DATA statements, are in a quoted string, or are at the end of a
  200. line (since the underscore represents a line continuation character in some
  201. versions of BASIC).
  202.  
  203. The name replacement capability can make it easy to rearrange your program
  204. without actually having to modify it beyond a #DEFINE or two.  For instance,
  205. if you want to create a version of your program where all PRINTs are directed
  206. to the printer, you might say:
  207.  
  208. #DEFINE PRINT LPRINT
  209.  
  210. The conditional compilation can be very handy if your program may be compiled
  211. by different compilers.  With a simple #IFDEF or so, you can convert the
  212. program to take advantage of the features offered by a specific compiler (or
  213. to manage idiosyncracies of a specific compiler) by passing a /D define
  214. switch to BPP.  With BC 7.x ("PDS"), for example, you might want to use the
  215. built-in "END #" option to return an error code from your program.  With the
  216. QB 4.5 compiler, however, you'd have to use an external routine such as that
  217. provided by my PBClone library.  So, you might do something like this:
  218.  
  219. ' this would go at the top of the program
  220. #IFNDEF PDS
  221.    DECLARE SetError (BYVAL ErrorLevel%)
  222. #ENDIF
  223.  
  224. ' this would go at the end of the program
  225. #IFDEF PDS
  226.    END ErrorLevel%
  227. #ENDIF
  228. #IFNDEF PDS
  229.    SetError ErrorLevel%
  230.    END
  231. #END IF
  232.  
  233. To create the proper .BAS file for BC 7.x, you'd say "BPP filename /dPDS".
  234. To create the proper .BAS file for QB 4.5, you'd say "BPP filename".
  235.  
  236. These are just some ideas for you, of course.  There are many different ways
  237. to use the various preprocessor capabilities.
  238.  
  239.                            BPP: Miscellaneous Notes                     page 7
  240.                            =----------------------=
  241.  
  242.  
  243.  
  244.  
  245. WARNING!  The BPP utility does not expect to have to deal with numeric
  246. constants in exponential format.  In other words, if you have enabled name
  247. translation, don't have numbers like "1.2E-10" in your program.  Having a
  248. letter in the middle of a number may confuse BPP.
  249.  
  250. If you enable underscores in variable names, you may also use underscores in
  251. line labels (but not line numbers).  In fact, you may use them in FUNCTION
  252. and SUB names, BASIC statements, and anything else that follows the same
  253. format.  The values of preprocessor variables are immune to such treatment,
  254. since (if strings) they are treated as string constants.  Note that
  255. underscores may only be in the middle of names, not at the beginning or end
  256. of names.
  257.  
  258. ATTENTION!  The rest of this page discusses features which are NOT yet in
  259. BPP.  They may well be added later if there is sufficient interest.
  260.  
  261. The BPP utility gives you many of the capabilities of the full-fledged
  262. preprocessor defined in the ANSI C standard.  It follows the ANSI C
  263. conventions somewhat loosely-- after all, BASIC is not C, and should not be.
  264. BPP is not quite up to a good C preprocessor yet, but is more complete than
  265. the preprocessor provided with Turbo Pascal 6.0.
  266.  
  267. The missing capabilities lie in two areas.  One area covers full #IF, #ELSE
  268. and #ELIF (else if) conditionals, complete with evaluation of conditional
  269. expressions.  For example, "#IF QBVER = 4.5" represents a simple conditional
  270. which might be supported in a more complete preprocessor.
  271.  
  272. The other area is in macro handling, which is where a preprocessor can
  273. provide some serious extensions to a language.  Macro handling allows you to
  274. create routines that are not dependent on variable types, among other things.
  275. Suppose you wanted a MIN routine which would return the least of two values,
  276. regardless of whether you're dealing with strings, integers, single precision
  277. values, or whatever.  That could be done with a macro:
  278.  
  279. #DEFINE MIN(a,b,c) IF a < b THEN c = a ELSE c = b
  280.  
  281. There are additional capabilities that might be provided through various
  282. #PRAGMA options.  If you can think of any that might be useful, let me know.
  283.  
  284. I hope to include these additional preprocessor capabilities in later
  285. versions of BPP as I find the time to do so.  Please feel free to write me
  286. about any suggestions or comments you might have.  If you have access to a
  287. modem, you can reach me most readily through the BBSes listed in WHERE.BBS.
  288. You can also write me directly at the address given in REGISTER.TXT.
  289.  
  290.